feat(devx): pin the ported guard-main-checkout self-test, and stop --resync rewriting governed files - #7954

Fixes #7263

scripts/upstream-port-pin.json covered only scripts/, so the verbatim cross-repo ports under .claude/hooks/** — this repo's densest concentration of copies from one upstream, and the directory whose drift history is four separate human catches (#5459, #5712, #5789, #6042) — had no drift gate. Two changes, in the order they have to happen.

1. --resync refuses to rewrite governed surface

Registering a file EDITS nothing; --resync REWRITES one in place, from another repository's bytes. Only the second is a governed-surface act. --resync now refuses any ported path on the governed surface unless --rewrite-governed-file is passed, naming the path, the surface it matched and the flag. The governed set is read from governedPathsIn in scripts/check-governed-queue-guard.mjs — the repo's own definition, reused rather than re-listed, so the two cannot disagree.

The CHECK path is untouched. A drifted governed port reds with no flag and no exemption; two self-test rows pin exactly that, because a gate that went quiet on the surface with the worst drift history would be this mechanism inverted.

Measured on this branch, all three legs:

$ node scripts/check-upstream-port-parity.mjs --resync /tmp/up-hook.sh --ref bf10debd5… \
    --path .claude/hooks/guard-main-checkout.selftest.sh                     # EXIT 2
⛔ refusing to rewrite .claude/hooks/guard-main-checkout.selftest.sh: it is GOVERNED SURFACE
   (.claude/** — the agent instruction tree (skills, hooks, settings)), which this repository
   merges by human review.
  • To do it anyway — as the human doing that merge — pass --rewrite-governed-file.
  • Registering this file in the pin is NOT affected: checking is not writing, and a
    drifted governed port reds this gate with no flag and no exemption.
$ git status --porcelain      # empty — the refusal is proved by state, not by the exit code

$ … --rewrite-governed-file                                                  # EXIT 0
.claude/hooks/guard-main-checkout.selftest.sh is GOVERNED SURFACE (…) and --rewrite-governed-file
was passed: rewriting it in place.
✓ re-synced … (14 divergence(s) re-applied) and bumped the pin.
    blob before 4844703e2a72bb… → after 4844703e2a72bb…   (same ref in, byte-identical out)

$ … --resync /tmp/up-invoked-as.mjs --path scripts/invoked-as.mjs            # EXIT 0
✓ re-synced scripts/invoked-as.mjs … — no refusal: a non-governed path is unchanged.

2. The first .claude/** entry, and what re-deriving it actually measured

⚠️ The card's readiness measurement no longer holds, and this is the delta it asked for. #7263 measured this file at "exactly 4 declared divergences, all comment / echo-label text, no executable line differs", at upstream d63c8a2. Re-derived today:

• The pinned upstream blob at bf10debd5 and the blob at d63c8a2 are byte-identical for this file, so the pin's ref is not the reason the count moved.
• What moved is THIS side: PR fix(hooks): guard-main-checkout reads the path key its routed tool carries #7686 (fix(hooks): read the edited path from the key the routed tool carries) landed after the port and rewrote the matrix — the nbpay helper, the routed-tool drift arm, the matcher/known_path_keys pairing, the notebook verdict section, and the removal of the hole section that finding(hooks): guard-main-checkout.sh never reads notebook_path, so every NotebookEdit is judged by CLAUDE_PROJECT_DIR — wrong in BOTH directions, though the matcher routes that tool to it #7260 pinned.

So the entry is registered with 14 declared divergences, not 4, and 12 of them cover executable text. Each carries its one-sentence why; twelve name #7686, two name the port itself (the provenance header, and the KNOWN HOLE re-pointing at this repo's own #7259 with upstream's number kept as a cross-reference). The gate's green line is exactly true and says what it verified:

✓ .claude/hooks/guard-main-checkout.selftest.sh: byte-identical to
  objectstack-ai/objectstack@bf10debd5:.claude/hooks/guard-main-checkout.selftest.sh
  modulo 14 declared divergence(s).
✓ check-upstream-port-parity: 3 ported file(s) match objectstack-ai/objectstack@bf10debd5
  modulo their declared divergences.

⚠️ What that row does NOT say: that this hook matches upstream today. Against upstream main (a4816a79d) the same file still differs by 102 lines (40 executable), two of them live and already tracked — the substring worktree hole (#7259, and PR #7749 is in flight on it) and the escape-hatch remedy sentence (#7775). The pin's single upstream.ref cannot see either. That, plus the drift table for the other seven hooks, is filed as #7953.

Reverse verification

Mutated on disk, gate read, restored with git checkout HEAD -- PATH, restore proved by blob hash (4844703e2a72bb…) and an empty git diff HEAD each time. All three drift directions reached:

⚠️ Two honest notes on this table. The first mutation was chosen expecting the digest-mismatch direction and landed inside a declared region instead — the observed direction is reported, not the predicted one. And a fourth attempt produced no diff at all (a perl one-liner whose escaping silently matched nothing, exit 0); it was caught by counting the deleted and injected text on disk rather than by trusting the editor's exit code, and re-run.

Wiring: one assertion re-scoped, one added

upstream-port-parity-wiring.test.ts asserted pinned ⊆ half-state-patrol.paths. That silently encoded "the ledger only ever pins the sweeper's unit" — true of the two entries that existed, not a property of the ledger — and it reds on the first entry outside scripts/. It is re-scoped to the patrol's own unit in both directions, and the claim that matters for entries beyond it is now asserted directly: no pinned file falls inside lint.yml's ignore set, so the pull request that drifts a pinned file is never the one on which the gate does not run. That test carries a control leg — each ignore glob must recognise a file it exists to ignore — because the first version of its glob matcher matched nothing and passed.

Serial note

⚠️ PR #7749 (draft, another seat) edits this same self-test's KNOWN HOLE section. This entry is derived against main as of f10e49f36, deliberately not against that branch; when #7749 lands, divergences hole-heading-repointed, hole-crossref-repointed and their neighbours need re-deriving, and the gate will say so loudly rather than quietly (expected its ported text exactly once, found 0).

Gates

Run at 4263ff3f4. No file under .claude/** is edited by this pull request — the ported file is registered, not touched.

Generated by Claude Code